/
/ $Header: rdbms/demo/rac_wrappers/README.txt /main/2 2010/04/22 23:33:33 swshekha Exp $
/
/ README.txt
/
/ Copyright (c) 2009, Oracle. All Rights Reserved.
/
/   NAME
/     README.txt - <one-line expansion of the name>
/
/   DESCRIPTION
/     <short description of component this file declares/defines>
/
/   NOTES
/     <other useful comments, qualifications, etc.>
/
/   MODIFIED   (MM/DD/YY)
/   sswaroop    11/11/09 - Creation
/

              HOW TO USE RAC_WRAPPER PACKAGE

1. Installation:
  The installation script creates a user wrapperuser, grants required
  privileges and installs the package in that user. This script creates
  tables shrd$_map_table and shrd$_type_table in wrapperuser schema

  shrd$_map_table: This table contains the mappings between 
  logical and physical queue_tables/queues for all schemas

  shrd$_type_table: This table contains a list of all the payload types
  and their owners. Rows are inserted in this table when user grants 
  execute privilege on payload type to wrapperuser before calling 
  make_sharded_queue/create_queue_table. This is used for runtime creation 
  of dbms_aq package.
 
  Run the following script :
    racwrapper_setup.sql 
   
2. APIs:
  The following APIs are provided:

   a. make_sharded_queue: This procedure creates shards of the queue table,
      given as argument, in all the active instances except the owner of the 
      queue table.
      Syntax
       dbms_aqadm.make_sharded_queue(qt_name IN VARCHAR2)

      Prerequisite:
      Before calling make_sharded_queue for the first time, grant execute
      privilege to wrapperuser on all the types accesible to the user.
      run the following query to find out all the types accesible:

        SELECT distinct t.owner, t.type_name
         from all_queue_tables qt, all_types t
          where t.owner||'.'||t.type_name  = qt.OBJECT_TYPE;
      
      OR grant execute any type to wrapperuser.

      If the execute privilege is not granted to wrapperuser the following
      error(20051) is thrown
        'Insufficient Privileges: Grant execute privilege to wrapperuser on
         all the types accesible to <qt_schema>
        
   b. remove_sharded_queue: This procedure removes shards of a queue table 
      passed as argument. It periodically checks for empty shards and removes 
      them.
      Syntax
       dbms_aqadm.remove_sharded_queue(qt_name  IN VARCHAR2)

      Prerequisite:
      User must have create job privilege.

   c. alter_map_table :This procedure alters the properties of a sharded queue 
      table alongwith changes in map table. User must ensure that each instance 
      contains one and only one shard of the queue table.

      Syntax:
       alter_map_table(
               queue_table        IN  VARCHAR2, 
               primary_instance   IN  BINARY_INTEGER DEFAULT NULL,
               secondary_instance IN  BINARY_INTEGER DEFAULT NULL)


      NOTE: alter_queue_table only changes the queue table properties. If 
      primary or secondary instance of a queue table, which is sharded, is 
      changed, shard$_map_table is not updated with new instance numbers.

   d. recover_sharded_queue: This procedure can be called if
      make_sharded_queue fails. This will clear up all the shards and its 
      meta-data.  
     Syntax
       dbms_aqadm.recover_sharded_queue(qt_name  IN VARCHAR2)
   

3. Usage:
   a. Privileges Required
   1. For remove_sharded_queue user must have create job privilege
   2. Before calling make_sharded_queue for the first time, grant execute
      privilege to wrapperuser on all the types accesible to the user.
      run the following query to find out all the types accesible:
      
        SELECT distinct t.owner, t.type_name 
         from all_queue_tables qt, all_types t
          where t.owner||'.'||t.type_name  = qt.OBJECT_TYPE;

      OR dba/sys can grant execute any type to wrapperuser.

   3. Before calling create_queue_table(after package installation) with
      a new payload type grant excute on that type to wrapperuser.
   
  b. After installation is successful, 
    1.connect to the aqadmin user.
    2.create synonym dbms_aqadm for wrapperuser.dbms_aqadm_wrapper.
       grant execute privilege to wrapperuser on all accesible types(as
       described above)
    3.call dbms_aqadm.make_sharded_queue for an existing queue table 
       to create shards on the rac instances.
    4.connect as aquser
    5.create synonym dbms_aq for wrapperuser.dbms_aq_wrapper.
    6.Run enqueues and dequeues
    7.connect as aqdmin
    8.call dbms_aqadm.remove_sharded_queue to remove the shards

4. Query Shard:
     A package named shrdinfo is provided to query shrd$_map_table. Procedures 
     in the package are:

     print: This will print all the columns of shrd$_map_table.

     get_physical_qt(owner IN VARCHAR, qtab IN VARCHAR): 
     Given queue table name and schema, this function returns physical 
     queue table name corresponding to the queue table in that instance.

     get_physical_q(owner IN VARCHAR, qnm IN VARCHAR): 
     Given queue name and schema, this function returns physical 
     queue name corresponding to the queue in that instance.
     

5. Limitations:
  a. make_sharded_queue call doesn't replicate notifications for the shards.
     It has to be done manually.
  b. No support for enqueue array and dequeue array.
  c. A queue table should not be sharded if streams use queues in it.
  d. Shard to shard propagation is not supported i.e. if there is propagation
     between two sharded queues then messages are propagated to the base queue 
     only.
  e. End/deq privileges for aquser are not replicated after sharding. Hence
     they should be granted again.
  f. Drop user DDL doesn't remove entries from shrd$_map_table and
     shrd$_type_table for that user.
     Entries should be mannually deleted by a simple query: 
     delete from shrd$_map_table where owner = <usr_name>;
     delete from shrd$_type_table where owner = <usr_name>;

6. Uninstall:   
   1. Ensure that no end/deq and admin activity is running in the schemas
      which are using the package because it will drop all the synonyms.
   2. Connect as sys and run the uninstall script -- racwrapper_uninstall.sql. 
      This script uninstalls the wrapper package, drops the synonyms and 
      drops wrapperuser.
  
7. Example:
      File racwrapper_test.sql is provided to demonstrate the usage of
      this package
-------------------------------------------------------------------------------
                                NOTE 
-------------------------------------------------------------------------------
 Instead of finding out all accessible types and granting execute privilege on 
 each type, dba may grant execute any type to wrapperuser. 

 It may be the case that user has execute privilege on a type (granted by 
 another user) without grant option. Then either the owner of the type has to 
 grant privilege on specific type or dba can grant execute any type privilege 
 to wrapperuser.

 If a user is dropped then delete entries from shrd$_type_table for that user 
 and if remove_sharded_queue hasn't been called delete entries from 
 shrd$_map_table as well.
-------------------------------------------------------------------------------


